'\" t
.\"     Title: ALTER FOREIGN TABLE
.\"    Author: The PostgreSQL Global Development Group
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
.\"      Date: 2011-12-01
.\"    Manual: PostgreSQL 9.1.2 Documentation
.\"    Source: PostgreSQL 9.1.2
.\"  Language: English
.\"
.TH "ALTER FOREIGN TABLE" "7" "2011-12-01" "PostgreSQL 9.1.2" "PostgreSQL 9.1.2 Documentation"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
ALTER_FOREIGN_TABLE \- change the definition of a foreign table
.\" ALTER FOREIGN TABLE
.SH "SYNOPSIS"
.sp
.nf
ALTER FOREIGN TABLE \fIname\fR
    \fIaction\fR [, \&.\&.\&. ]
ALTER FOREIGN TABLE \fIname\fR
    RENAME [ COLUMN ] \fIcolumn\fR TO \fInew_column\fR
ALTER FOREIGN TABLE \fIname\fR
    RENAME TO \fInew_name\fR
ALTER FOREIGN TABLE \fIname\fR
    SET SCHEMA \fInew_schema\fR

where \fIaction\fR is one of:

    ADD [ COLUMN ] \fIcolumn\fR \fItype\fR [ NULL | NOT NULL ]
    DROP [ COLUMN ] [ IF EXISTS ] \fIcolumn\fR [ RESTRICT | CASCADE ]
    ALTER [ COLUMN ] \fIcolumn\fR [ SET DATA ] TYPE \fItype\fR
    ALTER [ COLUMN ] \fIcolumn\fR { SET | DROP } NOT NULL
    OWNER TO \fInew_owner\fR
    OPTIONS ( [ ADD | SET | DROP ] \fIoption\fR [\*(Aq\fIvalue\fR\*(Aq] [, \&.\&.\&. ])
.fi
.SH "DESCRIPTION"
.PP

ALTER FOREIGN TABLE
changes the definition of an existing foreign table\&. There are several subforms:
.PP
ADD COLUMN
.RS 4
This form adds a new column to the foreign table, using the same syntax as
CREATE FOREIGN TABLE (\fBCREATE_FOREIGN_TABLE\fR(7))\&.
.RE
.PP
DROP COLUMN [ IF EXISTS ]
.RS 4
This form drops a column from a foreign table\&. You will need to say
CASCADE
if anything outside the table depends on the column; for example, views\&. If
IF EXISTS
is specified and the column does not exist, no error is thrown\&. In this case a notice is issued instead\&.
.RE
.PP
SET DATA TYPE
.RS 4
This form changes the type of a column of a foreign table\&.
.RE
.PP
SET/DROP NOT NULL
.RS 4
Mark a column as allowing, or not allowing, null values\&.
.RE
.PP
OWNER
.RS 4
This form changes the owner of the foreign table to the specified user\&.
.RE
.PP
RENAME
.RS 4
The
RENAME
forms change the name of a foreign table or the name of an individual column in a foreign table\&.
.RE
.PP
SET SCHEMA
.RS 4
This form moves the foreign table into another schema\&.
.RE
.PP
OPTIONS ( [ ADD | SET | DROP ] \fIoption\fR [\*(Aq\fIvalue\fR\*(Aq] [, \&.\&.\&. ] )
.RS 4
Change options for the foreign table\&.
ADD,
SET, and
DROP
specify the action to be performed\&.
ADD
is assumed if no operation is explicitly specified\&. Option names must be unique; names and values are also validated using the foreign data wrapper library\&.
.RE
.PP
All the actions except
RENAME
and
SET SCHEMA
can be combined into a list of multiple alterations to apply in parallel\&. For example, it is possible to add several columns and/or alter the type of several columns in a single command\&.
.PP
You must own the table to use
ALTER FOREIGN TABLE\&. To change the schema of a foreign table, you must also have
CREATE
privilege on the new schema\&. To alter the owner, you must also be a direct or indirect member of the new owning role, and that role must have
CREATE
privilege on the table\*(Aqs schema\&. (These restrictions enforce that altering the owner doesn\*(Aqt do anything you couldn\*(Aqt do by dropping and recreating the table\&. However, a superuser can alter ownership of any table anyway\&.)
.SH "PARAMETERS"
.PP
\fIname\fR
.RS 4
The name (possibly schema\-qualified) of an existing foreign table to alter\&.
.RE
.PP
\fIcolumn\fR
.RS 4
Name of a new or existing column\&.
.RE
.PP
\fInew_column\fR
.RS 4
New name for an existing column\&.
.RE
.PP
\fInew_name\fR
.RS 4
New name for the table\&.
.RE
.PP
\fItype\fR
.RS 4
Data type of the new column, or new data type for an existing column\&.
.RE
.PP
CASCADE
.RS 4
Automatically drop objects that depend on the dropped column (for example, views referencing the column)\&.
.RE
.PP
RESTRICT
.RS 4
Refuse to drop the column if there are any dependent objects\&. This is the default behavior\&.
.RE
.PP
\fInew_owner\fR
.RS 4
The user name of the new owner of the table\&.
.RE
.PP
\fInew_schema\fR
.RS 4
The name of the schema to which the table will be moved\&.
.RE
.SH "NOTES"
.PP
The key word
COLUMN
is noise and can be omitted\&.
.PP
Consistency with the foreign server is not checked when a column is added or removed with
ADD COLUMN
or
DROP COLUMN, a
NOT NULL
constraint is added, or a column type is changed with
SET DATA TYPE\&. It is the user\*(Aqs responsibility to ensure that the table definition matches the remote side\&.
.PP
Refer to
CREATE FOREIGN TABLE (\fBCREATE_FOREIGN_TABLE\fR(7))
for a further description of valid parameters\&.
.SH "EXAMPLES"
.PP
To mark a column as not\-null:
.sp
.if n \{\
.RS 4
.\}
.nf
ALTER FOREIGN TABLE distributors ALTER COLUMN street SET NOT NULL;
.fi
.if n \{\
.RE
.\}
.PP
To change options of a foreign table:
.sp
.if n \{\
.RS 4
.\}
.nf
ALTER FOREIGN TABLE myschema\&.distributors OPTIONS (ADD opt1 \*(Aqvalue\*(Aq, SET opt2, \*(Aqvalue2\*(Aq, DROP opt3 \*(Aqvalue3\*(Aq);
.fi
.if n \{\
.RE
.\}
.SH "COMPATIBILITY"
.PP
The forms
ADD,
DROP, and
SET DATA TYPE
conform with the SQL standard\&. The other forms are
PostgreSQL
extensions of the SQL standard\&. Also, the ability to specify more than one manipulation in a single
ALTER FOREIGN TABLE
command is an extension\&.
.PP

ALTER FOREIGN TABLE DROP COLUMN
can be used to drop the only column of a foreign table, leaving a zero\-column table\&. This is an extension of SQL, which disallows zero\-column foreign tables\&.
